About Hit-Testing Picture Shapes (IM: XG)

Inside Macintosh: QuickDraw GX Graphics /: Chapter 6 - Picture Shapes / About Picture Shapes

About Hit-Testing Picture Shapes
When the user clicks the mouse, your application receives the information from the Macintosh Toolbox about where the mouse click occurred. By sending this information to the GXHitTestPicture function, you can find out which item in a picture was hit. This process is called hit-testing a picture shape.
When hit-testing a picture shape, QuickDraw GX searches through the shapes contained in the picture until it finds the shape that was hit by the hit-test point. As QuickDraw GX searches through the shapes in the picture, it

hit-tests the shape, using the hit-test information in that shape's transform object (or overriding transform object, if the shape has one) to determine if the shape was hit or not
determines whether the hit shapes satisfy criteria that you specify

QuickDraw GX returns information about the first item that was hit and satisfies the criteria.
Since more than one shape in a picture can be hit during a single hit-test, you provide QuickDraw GX with extra selection criteria when hit-testing a picture. Specifically, you specify a depth and a level:

Pictures frequently contain shapes that overlap when drawn. Therefore, it is possible that the test point hits multiple shapes. For example, if the picture contains two shapes, one on top of the other, the test point might hit both of them. You can control which of these shapes QuickDraw GX selects as the hit shape by specifying a shape depth. In this example, specifying a shape depth of 1 would indicate that QuickDraw GX should select the shape that was drawn on top as the hit shape. Specifying a shape depth of 2 would indicate that QuickDraw GX should select the shape that was drawn underneath as the hit shape.
In a picture hierarchy, each shape can be contained by a picture shape, which in turn can be contained by another picture shape, and so on. If the hit shape has a level of 3, for example, you can specify that QuickDraw GX return a reference to the hit shape by specifying a level of 3. You can specify that QuickDraw GX return a reference to the picture that contains the hit shape by specifying a level of 2. You can specify that QuickDraw GX return a reference to the picture that contains the picture that contains the hit shape by specifying a level of 1.

Figure 6-18 shows an example. The picture shape shown in this figure has two items, each of which are pictures. Each of these pictures has two items itself, making a total of four shapes that have a level of 2 in this hierarchy.
This figure shows the picture as drawn, and three sample hit-test points.
Figure 6-18 A picture shape and hit-test points

The first sample hit-test point hits only one shape: the lawn path shape. If you specified a depth of 1, QuickDraw GX would select this shape as the hit shape. The shape returned by QuickDraw GX, however, depends on what you specify for the level. If you specify 2, the lawn path shape would be returned. If you specified 1, however, the picture that contains the lawn path shape would be returned.
The second sample hit-test point hits two shapes: at depth 1, it hits the house rectangle; at depth 2, it hits the lawn shape. You determine which is the hit shape by specifying a depth of 1 or 2. You also specify whether QuickDraw GX returns the hit shape (by specifying level 2) or the picture that contains the hit shape (by specifying level 1).
The third hit-test point hits three shapes: at depth 1, it hits the house rectangle; at depth 2, it hits the walkway polygon; at depth 3, it hits the lawn shape. Again, you can determine which of these shapes is the hit shape (by specifying the depth) and whether the hit shape or the picture that contains it is returned (by specifying the level).
For programming examples of hit-testing picture shapes, see "Hit-Testing Pictures" beginning on page 6-46.